\chapter{Cursor Stored Procedures}
\label{ap:cursorsp}

Existem instalados no SQL Server um conjunto de \glspl{storedprocedure} que permitem a operação de um cursor sobre um \emph{dataset} \cite{MSCURSOR,JTDSCURSOR}. Este é um tema que não está directamente relacionado com a descrição do protocolo TDS, mas do ponto de vista da implementação de um driver JDBC, estes dois temas estão intimamente ligados.

A mensagem de \emph{rpc request} do TDS possui um campo em que se pode indicar um número de um \gls{storedprocedure}, esse stored procedure é um dos que se podem encontrar em \cite{MSCURSOR} e cujo número identificador se pode encontrar na respectiva documentação.

Estes \emph{stored procedures} são o elemento fundamental na implementação de um result set \emph{scrollable} e/ou \emph{updatable}.

Na Tabela \ref{tab:cursorsp} são apresentados os stored procedures importantes para a implementação do driver. A coluna {\bf procId} corresponde ao identificador do stored procedure.

\begin{table}[H]
  \caption{\emph{Stored prodecures} do sistema relevantes para a implementação do driver JDBC.}
  \label{tab:cursorsp}
  \centering
  \begin{tabular}{|l|l|p{9cm}|}
    \hline 
    \head{procId} & \head{Nome} & \head{Descrição}
    \\ \hline
    1 & sp\_cursor & Permite efectuar actualização, inserção ou remoção de uma ou mais linhas do \emph{fetch buffer} do cursor.
    \\ \hline
    2 & sp\_cursoropen & Abre um cursor definindo a \emph{statement} SQL a ele associada e suas opções.
    \\ \hline
    7 & sp\_cursorfetch & Carrega uma ou mais linhas para o \emph{buffer} do cursor. Este \emph{buffer} designa-se de \emph{fetch buffer}.
    \\ \hline
    9 & sp\_cursorclose & Fecha e liberta os recursos associados ao cursor.
    \\ \hline
  \end{tabular}
\end{table}

A seguir será apresentada e explicada a sintaxe de cada um dos \emph{stored procedures} aqui enunciados.


\section{sp\_cursor}
\label{sec:spcursor}

Mais informações sobre este \emph{stored procedure} podem ser encontradas em \cite{SPCURSOR}.

\subsection{Sintaxe}
\begin{verbatim}
sp_cursor  cursor, optype, rownum, table
    [ , value [...n] ] ]
\end{verbatim}

\subsection{Argumentos}
\begin{itemize}
  %cursor
  \item[] \emph{cursor} \\
  Identificador do cursor gerado pelo SQL Server na execução do \texttt{sp\_cursor}.

  %optype
  \item[] \emph{optype} \\
  Identifica a operação a executar: \\
  \begin{tabular}{|l|l|p{8cm}|}
    \hline
    \head{Valor} & \head{Operação} & \head{Descrição}
    \\ \hline
    0x0001 & UPDATE & Actualiza uma ou mais linhas indicadas por \emph{rownum}.
    \\ \hline
    0x0002 & DELETE & Remove uma ou mais linhas indicadas por \emph{rownum}.
    \\ \hline
    0x0004 & INSERT & Insere dados.
    \\ \hline
    0x0008 & REFRESH & Volta a preencher o \emph{fetch buffer} com os dados das tabelas.
    \\ \hline
    0x10 & LOCK & Provoca a aquisição de um SQL Server U-Lock nas páginas que contêm a linhas especificadas.
    \\ \hline
    0x20 & SETPOSITION & Pode ser usado numa cláusula OR com REFRESH, UPDATE, DELETE ou LOCK para mudar a posição do cursor para a última linha modificada.
    \\ \hline
    0x40 & ABSOLUTE & Pode ser usado numa cláusula OR com UPDATE ou DELETE para modificar a linha indicada por \emph{rownum}, e cujo valor é referente ao \emph{data set} criado pela SQL \emph{statement} em vez de se referir ao \emph{fetch buffer}.
    \\ \hline
  \end{tabular}

  %rownum
  \item[] \emph{rownum} \\
  Especifica a linha do \emph{fetch buffer} sobre a qual se irá realizar a operação.

  %table
  \item[] \emph{table}
  Nome da tabela sobre a qual será realizada a operação. Relevante quando a \emph{statement SQL} involve um \emph{join}.

  %value
  \item[] \emph{value}
  String em Unicode que indica os valores de actualização/inserção.
\end{itemize}


\section{sp\_cursoropen}
\label{sec:spcursoropen}

Mais informações sobre este \emph{stored procedure} podem ser encontradas em \cite{SPCURSOROPEN}.

\subsection{Sintaxe}
\begin{verbatim}
sp_cursoropen cursor OUTPUT, stmt 
    [, scrollopt [ OUTPUT ] [ , ccopt [ OUTPUT ] 
    [ ,rowcount OUTPUT [ ,boundparam] [,...n] ] ] ] ] 
\end{verbatim}

\subsection{Argumentos}
\begin{itemize}
  %cursor
  \item[] \emph{cursor} \\
  Identificador do cursor gerado pelo SQL Server na execução do \texttt{sp\_cursor}.

  %stmt
  \item[] \emph{stmt} \\
  SQL statement que define o result set do cursor.

  %scrollopt
  \item[] \emph{scrollopt} \\
  Indica o tipo de cursor criado: \\
  \begin{tabular}{|l|l|}
  \hline
  \head{Valor} & \head{Descrição}
  \\ \hline
  0x0001 & KEYSET
  \\ \hline
  0x0002 & DYNAMIC
  \\ \hline
  0x0004 & FORWARD\_ONLY
  \\ \hline
  0x0008 & STATIC
  \\ \hline
  0x10 & FAST\_FORWARD
  \\ \hline
  0x1000 & PARAMETERIZED\_STMT
  \\ \hline
  0x2000 & AUTO\_FETCH
  \\ \hline
  0x4000 & AUTO\_CLOSE
  \\ \hline
  0x8000 & CHECK\_ACCEPTED\_TYPES
  \\ \hline
  0x10000 & KEYSET\_ACCEPTABLE
  \\ \hline
  0x20000 & DYNAMIC\_ACCEPTABLE
  \\ \hline
  0x40000 & FORWARD\_ONLY\_ACCEPTABLE
  \\ \hline
  0x80000 & STATIC\_ACCEPTABLE
  \\ \hline
  0x100000 & FAST\_FORWARD\_ACCEPTABLE
  \\ \hline
  \end{tabular}

  %ccopt
  \item[] \emph{ccopt} \\
  Indica o tipo de concorrência do cursor criado: \\
  \begin{tabular}{|l|l|}
  \hline
  \head{Valor} & \head{Descrição}
  \\ \hline
  0x0001 & READ\_ONLY
  \\ \hline
  0x0002 & SCROLL\_LOCKS
  \\ \hline
  0x0004 & OPTIMISTIC
  \\ \hline
  0x0008 & OPTIMISTIC
  \\ \hline
  0x2000 & ALLOW\_DIRECT
  \\ \hline
  0x4000 & UPDT\_IN\_PLACE
  \\ \hline
  0x8000 & CHECK\_ACCEPTED\_OPTS
  \\ \hline
  0x10000 & READ\_ONLY\_ACCEPTABLE
  \\ \hline
  0x20000 & SCROLL\_LOCKS\_ACCEPTABLE
  \\ \hline
  0x40000 & OPTIMISTIC\_ACCEPTABLE
  \\ \hline
  0x80000 & OPTIMISITC\_ACCEPTABLE
  \\ \hline
  \end{tabular}

  %rowcount
  \item[] \emph{rowcount}
  Número de linhas do \emph{fetch buffer} a ser usado pelo AUTO\_FETCH.

  %boundparam
  \item[] \emph{boundparam}
  Significa o uso de parâmetros adicionais.
\end{itemize}


\section{sp\_cursorfetch}

Mais informações sobre este \emph{stored procedure} podem ser encontradas em \cite{SPCURSORFETCH}.

\subsection{Sintaxe}
\begin{verbatim}
sp_cursorfetch cursor 
    [ , fetchtype [ , rownum [ , nrows ] ] ] 
\end{verbatim}

\subsection{Argumentos}
\begin{itemize}
  %cursor
  \item[] \emph{cursor} \\
  Identificador do cursor gerado pelo SQL Server na execução do \texttt{sp\_cursor}.

  %fetchtype
  \item[] \emph{fetchtype} \\
  Especifica que o \emph{buffer} que deve ser carregado: \\
  \begin{tabular}{|l|l|p{8cm}|}
  \hline
  \head{Valor} & \head{Nome} & \head{Descrição}
  \\ \hline
  0x0001 & FIRST & Carrega o primeiro \emph{buffer} de \emph{nrows} linhas.
  \\ \hline
  0x0002 & NEXT & Carrega o próximo \emph{buffer} de \emph{nrows} linhas.
  \\ \hline
  0x0004 & PREV & Carrega o antecessor \emph{buffer} de \emph{nrows} linhas.
  \\ \hline
  0x0008 & LAST & Carrega o último \emph{buffer} de \emph{nrows} linhas.
  \\ \hline
  0x10 & ABSOLUTE & Carrega \emph{nrows} linhas a partir da linha \emph{rownum}. 
  \\ \hline
  0x20 & RELATIVE & Carrega \emph{nrows} linhas começando na linha \emph{rownum}.
  \\ \hline
  0x80 & REFRESH & Recarrega o \emph{buffer} com os dados das tabelas.
  \\ \hline
  0x100 & INFO & Obtém informação acerca do cursor.
  \\ \hline
  0x200 & PREV\_NOADJUST & Usado como PREV, mas ao contrário de PREV, esta opção não preenche o \emph{buffer} com linhas que se encontram na actual posição ou depois da actual posição do cursor.
  \\ \hline
  0x400 & SKIP\_UPDT\_CNCY & Quando usado os valores \emph{timestamp} das colunas não são escritos na tabela \emph{keyset} quando uma linhas é (re)carregada. Tem que ser utilizado em conjunção com umas das outras opções à excepção de INFO.
  \\ \hline
  \end{tabular}

  %rownum
  \item[] \emph{rownum} \\
  Usado para especificar a linha de ABSOLUTE ou RELATIVE.

  %nrows
  \item[] \emph{nrow} \\
  Especifica o número de linhas que devem ser carregadas pela operação. Por pré-definição tem o valor 20.

\end{itemize}


\section{sp\_cursorclose}

Mais informações sobre este \emph{stored procedure} podem ser encontradas em \cite{SPCURSORCLOSE}.

\subsection{Sintaxe}
\begin{verbatim}
sp_cursorclose cursor
\end{verbatim}

\subsection{Argumentos}
\begin{itemize}
  %cursor
  \item[] \emph{cursor} \\
  Identificador do cursor gerado pelo SQL Server na execução do \texttt{sp\_cursoropen}.
\end{itemize}
